Below I am showing a concrete snippet to validate messages. Can you include that here too, and prominently mention a link to the security-relevant best practices at https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#security_concerns

Ideally we should have a dedicated section on this manifest page that clarifies how this feature should be used:

• messages between the extension and sandboxed page should be strictly validated, with link to https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#security_concerns
• don't execute untrusted code. Although the extension does not have access to privileged APIs, the extension URL may identify the use of the extension and be abused for fingerprinting purposes.
• don't use sandboxed pages with a relaxed CSP if your only objective is the use of WebAssembly. Instead, add 'wasm-unsafe-eval' to the extension's content_security_policy instead.

Done

Is this intended as a placeholder example? The example on the page itself does not run because the definition of the file is missing.

It's now a fully working example. However, after debugging an issue I found with Claude, it responded that "sandbox.js rejected every message with if (event.origin !== location.origin) — but a sandboxed page has an opaque origin (serializes to "null"), while the sender (popup.html) has a real moz-extension:// origin, so that check could never pass and the render would never happen. I replaced it with event.source !== window.parent (and added the matching check on the popup.js side, event.source !== sandbox.contentWindow), which validates the sender by window identity instead of origin — this is what MDN's own postMessage() security-concerns guidance recommends specifically because origin comparisons don't work for opaque-origin frames."

Link "opaque origin" to https://developer.mozilla.org/en-US/docs/Glossary/Origin#opaque_origin

Also add a bullet point mentioning that web platform APIs bound to the origin are unavailable. For some examples, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox#allow-same-origin

Done

Wouldn't it be less confusing if we:

• declare one overview, and emphasize for the sandbox.content_security_policy key that it is MV2 only
• at that description, point to the section on content_security_policy.sandbox (on the same page) for the MV3 syntax
• note that the content_security_policy.sandbox is MV3-only, and that for MV2 the other key has to be used?

This would enable us to add new manifest keys to sandbox without being forced to duplicate that documentation in two sections. I anticipate that we will likely have a new manifest sub key in sandbox as part of https://bugzilla.mozilla.org/show_bug.cgi?id=2053336

Good point, done

The framing of template engine is likely copied from Chrome. Although that was a motivating factor back then (10+ years ago), it is hardly a relevant considerations now. These days such libraries are mostly designed to work even with a strict CSP. Let's drop the mention of templating libraries (the general reference to eval/Function are sufficient).

Done